Add the provider documentation set and finish the decomposition - #1047

Brings upd/split/3-permissions at a2a1dfc into split/4-client-resolve. That
renames `config/permissions/vanilla.yaml` to `config/permissions/sample.yaml`
and says in the file, in the guide and on the constant that the sample is for
testing and evaluation only, is not a production policy and is not legal
advice.

The merge had no conflicts. `trusted-server.example.toml` auto-merged, because
this branch changes other parts of the same file.

Tests. `cargo fmt --all --check` is clean and the core suite passes 2,885
tests.

configuration guide

Brings upd/split/4-client-resolve at e17090b into
split/5-response-hook-docs, which carries split/3's a2a1dfc renaming
`config/permissions/vanilla.yaml` to `config/permissions/sample.yaml`.

This branch adds the permissions paragraph in `docs/guide/configuration.md`,
which split/3 does not have, so the merge could not correct it. That sentence
now names the new path and says the sample is for testing and evaluation only
and is neither a production policy nor legal advice, matching the file header
and the permission model guide.

The merge had no conflicts. `trusted-server.example.toml` auto-merged.

Tests. `cargo fmt --all --check` is clean and the core suite passes 2,885
tests. The docs Prettier configuration sets `proseWrap: preserve`, so the
edited sentence cannot change the formatting of the file.

Every name an operator types into configuration is snake_case, so the
demonstration provider is now selected with `[ec] provider = "client_fixed"`.
The key constant, the two startup messages that spell the key, the page
script's log lines, the cargo feature comment, the provider table in AGENTS.md
and the resolve endpoint in the API reference all follow. This commit changes
only that one name.

The cargo feature that compiles the provider in keeps the name
`client-fixed-demo`, because a cargo feature name is not a configuration value.
The tsjs module id `ec_client_fixed` is unchanged as well, being already
snake_case and never compared against the key.

The old name is refused when settings load, which every adapter does through
`settings_from_config_blob` before it serves a request. The message names
`client_fixed` and says what to write, so a deployment still configured with
`client-fixed` stops at startup rather than being told to add a provider block
that this provider does not need. A block written under the old name does not
make the old name acceptable either, because the name is refused before any
block is looked for. That is a breaking change, accepted for a major release.

Tests. `cargo fmt --all -- --check` is clean and `cargo clippy -p
trusted-server-core --all-targets --all-features -- -D warnings` passes. The
core suite passes 2,886 tests and 8 doc-tests, with and without the
`client-fixed-demo` feature, the new test among them. The Axum adapter passes
62 tests, `cargo clippy-axum` is clean, and `cargo check -p
trusted-server-adapter-fastly --target wasm32-wasip1` builds. The page
script's own vitest file passes 6 tests and ESLint is clean on it.

Every provider type selects the same way, with provider in its own section,
and names its providers in snake_case. Permission signals now follow that,
so [permission_signal] sources becomes [permission_signal] provider. The key
stays an ordered list, and a configuration that leaves it out still runs
every provider the adapter links, in the order the adapter offers them.

The two hyphenated provider names become gpp_sale_opt_out and us_privacy,
while gpc and tcf are unchanged. The crates report the new identifiers, and
core's selection messages, the startup log, the module README, the guides,
the example configuration and the permissions sample follow.

sources is removed rather than accepted alongside provider, which breaks a
configuration written against the branch that introduced it. A section
carrying sources is refused when the settings are read, with a message
naming provider, on each path a deployment reads settings through, being a
TOML file, the TOML value ts config push reads, and the JSON config blob
read at startup. Reading the section by hand rather than with
deny_unknown_fields is what makes that message possible, because a derived
refusal can only name sources by declaring it as a field, and would then
offer it as a key it expects whenever it refused any other.

No provider takes settings, so a [permission_signal.<name>] block stays an
unknown field. Its refusal now says that a provider which gains settings
will take them there.

Tests cover the removed key on each of those paths, a settings block
refused as an unknown field, a list surviving a config blob round trip,
and, where the real crates are linked, the documented names selecting all
four providers in order and an old hyphenated name being refused with the
names available.

Every name an operator types into configuration is snake_case, so the built-in
host-signal provider is now selected with `[ec] provider = "host_signals"` and
configured with `[ec.providers.host_signals]`. The key constant, the serde name
of the typed block, the validation error key, the registered secret path
`ec.providers.host_signals.passphrase`, the placeholder-secret report, the two
startup messages that spell the key and the provider's own log line all follow.
This commit changes only that one name.

The `HostSignals` trait, the `host_signals` fields and arguments that carry it,
and the prose that calls this the host-signal provider are unchanged, because a
host capability is not a configuration value. The test secret-store key name
`host-signals-passphrase-key` is unchanged for the same reason, being a name an
operator picks for a secret rather than a provider name.

The Rust field name and the configuration name are now the same word, so the
`#[serde(rename)]` on the typed block goes and the field is declared the same
way as `hmac` beside it. That also retires the reason the `EcProviders`
validation keys were spelled out by hand, so the note above those keys is
rewritten to say what still holds, which is that each key has to match the
secret path `TrustedServerAppConfig::secret_fields` registers.

The old name is refused when settings load, which every adapter does before it
serves a request. The message names `host_signals` and says what to write. The
refusal comes before any block is looked for, because a block left behind under
the old name is captured as a vendor block, so the old selector would otherwise
find that block, pass the settings check, and fail later in provider resolution
with a message about an adapter that supplies no such provider. That is a
breaking change, accepted for a major release.

Tests. `cargo fmt --all -- --check` is clean and `cargo clippy -p
trusted-server-core --all-targets --all-features -- -D warnings` passes. The
core suite passes 2,764 tests and 5 doc-tests with 4 ignored, the new test among
them. The Axum adapter passes 43 tests across its three binaries, `cargo
clippy-axum` is clean, and `cargo check -p trusted-server-adapter-fastly
--target wasm32-wasip1` builds.

The Edge Cookie provider blocks move from [ec.providers.<name>] to
[ec.<name>], so identity follows the one convention every provider type
uses, where [<type>] provider = "<name>" selects and [<type>.<name>]
holds that provider's settings. The [ec.providers] table is gone, and a
configuration still carrying it is rejected with the new location in the
message.

A block exists only when the provider has settings. The built-in hmac
provider has a required passphrase, so selecting it still needs
[ec.hmac], while a provider with no settings needs no block at all. Only
the adapter that injects a provider knows whether that provider has
settings, so core no longer demands a block for a name it does not
supply itself.

A block may name the implementation it configures with
implementation = "<id>", which makes the block's own name a label of the
operator's choosing. [ec] provider = "primary" with [ec.primary] holding
implementation = "hmac" and a passphrase configures the built-in
provider under a name that means something to the deployment. Everything
that resolves the selection now reads the implementation rather than the
label, covering the built-in lookup, the matching of a provider the
adapter injects, the check that a selected implementation has the
settings it needs, and the errors. An implementation this deployment
cannot build fails startup naming the implementations it does have.

The fixed [ec] keys stay reserved and cannot name a provider, every
other key in the section has to be a table, and a key that is not one is
reported as the unknown field it almost certainly is, so a typo such as
ec_stor is still caught with a sensible message. Provider names and
implementation ids are snake_case. A block the selector does not name
still fails startup, as it did before.

Secrets follow the blocks. TrustedServerAppConfig::secret_fields now
lists ec.hmac.passphrase, and EdgeZero's path segments cannot say
"whatever name the operator chose", so core reads the labeled blocks out
of the configuration itself through the new ConfiguredSecretFields trait
and resolves their passphrases from trusted_server_secrets in the same
pass. Push-time validation, where those fields hold key names rather
than secrets, no longer runs the passphrase value check against a
labeled block's key name. The check itself is unchanged wherever
settings are loaded with their secrets resolved.

The legacy [ec] passphrase shim still works and now points at [ec.hmac].

Brings the Edge Cookie provider block layout, where each provider has its
own [ec.<name>] table and an optional implementation = "<id>" line, under
the host-signal provider rename this branch already carried. Both changes
are the same decision applied to different parts of one section, so the
host-signal provider is now selected with [ec] provider = "host_signals"
and configured in [ec.host_signals], not [ec.providers.host_signals].

Four files conflicted.

crates/trusted-server-core/src/settings.rs. split/1 replaced the typed
EcProviders struct with EcProviderBlocks, a map of the blocks written
under [ec], in which only the hmac implementation keeps typed settings
and everything else is held as the raw values an adapter reads. This
branch had added host_signals as a second typed built-in beside hmac, so
the resolution gives it the same standing in the new model rather than
demoting it to raw values. EcProviderSettings gains a HostSignals
variant, EcProviderBlock gains host_signals_settings, EcProviderBlocks
gains host_signals_blocks beside hmac_blocks, read_provider_block reads a
host_signals block into the typed config, and From<HostSignalsProviderConfig>
builds the block. The block-required check in validate_provider_selection
now covers both implementations built into core, because both take a
passphrase. The placeholder-secret report names the block the operator
wrote, as it already did for hmac. The refusal of the old host-signals
spelling is kept and its message now sends the operator to
[ec.host_signals]. That refusal moved to the top of
validate_provider_selection and now covers a block left under the old
name as well as the selector, because split/1's snake_case rule runs over
the block names first and would otherwise refuse host-signals with the
general rule instead of the message naming the spelling to write. The
tests of both branches are kept, with this branch's host-signal test
rewritten onto the new block layout.

crates/trusted-server-core/src/ec/provider.rs. Both branches edited the
resolution arms and the module documentation. build_provider keeps the
host_signals parameter this branch added, because the host-signal
provider needs a service only some hosts supply, and the host-signal arm
of resolve_named_provider now reads its settings out of the block the
selector names rather than a fixed field. BUILTIN_PROVIDER_KEYS keeps
both entries under split/1's wording, which calls them implementation
ids. The documentation keeps split/1's [ec.<name>] spelling together with
this branch's statement that the host-signal provider is built per
request.

crates/trusted-server-core/src/config.rs. The registered secret path for
the host-signal passphrase drops the removed providers segment and
becomes ec.host_signals.passphrase. Push-time validation reads the
host-signal blocks the same way it reads the hmac ones, and the reader
that finds a built-in provider configured under a label of the operator's
choosing now looks for either implementation, so a labeled host-signal
block resolves its passphrase too.

crates/trusted-server-core/src/config_payload.rs. Both branches added a
key to the test secret store. Both are kept, being separate keys serving
separate tests.

Two follow-on fixes outside the conflicts. The tests this branch had
written against the removed EcProviders type now go through a new
select_host_signals_provider test helper beside select_hmac_provider, and
the build_provider calls split/1 had reduced to two arguments take the
host_signals argument again.

Tests. cargo fmt --all -- --check is clean and cargo clippy -p
trusted-server-core --all-targets --all-features -- -D warnings passes.
The core suite passes 2,782 tests and 5 doc-tests with 4 ignored. The
Axum adapter passes 43 tests across its four binaries, cargo clippy-axum
is clean, and cargo check -p trusted-server-adapter-fastly --target
wasm32-wasip1 builds.

…it/2

Brings up the Edge Cookie provider block layout from split/1, where each
provider has its own [ec.<name>] table, together with split/2's rename of
the host-signal provider to host_signals. Both are the same decision this
branch applies to permission signals, which is that every provider name
an operator types is snake_case and a provider type is a top-level table
whose provider key selects what runs.

Nothing conflicted. The permission signal work this branch carries sits
in its own section and its own module, so the Edge Cookie section
changes merged alongside it.

One fix the merge needed. A test of the jurisdiction acknowledgment built
its stateless case by deleting the hmac provider block from the test
configuration by text, and it still named that block [ec.providers.hmac].
Under the new layout the block is [ec.hmac], so the deletion would have
matched nothing and left a provider block configured with no selector,
which the new layout rejects. The test now names the block it means.

Tests. cargo fmt --all -- --check is clean and cargo clippy -p
trusted-server-core --all-targets --all-features -- -D warnings passes.
The core suite passes 2,874 tests and 8 doc-tests with 4 ignored. The
Axum adapter passes 64 tests across its five binaries, cargo clippy-axum
is clean, and cargo check -p trusted-server-adapter-fastly --target
wasm32-wasip1 builds.

…rom split/3

Brings up the Edge Cookie provider block layout from split/1, the
host_signals rename from split/2 and the permission signal provider key
from split/3, under the client_fixed rename this branch already carried.
All four are the same decision, so this branch's demonstration provider
now sits in the same layout as the rest.

Two files conflicted.

crates/trusted-server-core/src/ec/provider.rs. Both branches added
constants and resolution arms. The client_fixed constants and its
resolution arm are kept, listed in BUILTIN_PROVIDER_KEYS beside the two
providers that derive an identifier at the edge, under split/3's wording,
which calls these implementation ids rather than names. The arm now
matches on the implementation the selected block names rather than the
selector itself, which is how the other arms read since the block layout
landed, so the demonstration provider can be configured under a label as
any other provider can.

check_named_provider_configuration needed a real decision. This branch
wrote it to answer two questions, which are whether the build compiles a
name in and whether the name needs a settings block, the second by
looking every name up in [ec.providers]. The block layout removed that
lookup and moved the block question back into the settings, where it is
now asked only of the implementations core knows take settings, because a
provider an adapter injects has its block read by that adapter and core
cannot say whether it needs one. Reinstating a block requirement for
every name would undo that, so the function keeps only the question this
branch added it for, which is whether the demonstration provider is
compiled into this build, and the settings ask the block question. The
function's own reasoning still holds for what it keeps, which is that
only the resolution knows what is compiled out.

The refusal of the old client-fixed spelling moved with it into the
settings, beside the refusal of the old host-signals spelling, and both
now run before anything else. They have to, because the block layout
holds every provider name to snake_case and both old spellings break that
rule, so leaving either refusal later meant an operator got the general
rule instead of the message naming the spelling to write. Both refusals
cover a block left behind under the old name as well as the selector,
through one names_retired_provider helper.

crates/trusted-server-core/src/settings.rs. The Ec struct keeps this
branch's resolve_allowed_origins field and loses the providers field the
block layout replaced. resolve_allowed_origins is a fixed key of the [ec]
section, so it joins EC_SECTION_KEYS, without which the section would read
it as a provider block.

Four of this branch's tests followed the new layout. The one that proves
a provider with no block validates now says why the settings no longer
demand one, the old-spelling test builds its configuration through the
[ec] section helper rather than by deleting the hmac block by text, the
missing-block error names [ec.hmac], and the stale-block test builds its
block through the shared test helper.

Tests. cargo fmt --all -- --check is clean and cargo clippy -p
trusted-server-core --all-targets --all-features -- -D warnings passes.
The core suite passes 2,909 tests and 8 doc-tests with 4 ignored. The
Axum adapter passes 64 tests across its five binaries, cargo clippy-axum
is clean, and cargo check -p trusted-server-adapter-fastly --target
wasm32-wasip1 builds.

…guides

Brings up the Edge Cookie provider block layout from split/1, the
host_signals rename from split/2, the permission signal provider key from
split/3 and the client_fixed rename from split/4. All four are the same
decision, which is that every provider name an operator types is
snake_case, a provider type is a top-level table, and a provider key
inside it selects what runs.

Nothing conflicted. The response hook and the documentation set this
branch carries sit beside the sections those renames touched.

The documentation needed the work the clean merge did not do. These
guides were written against the old layout, so they still told operators
to write a table that is now refused and to select providers by spellings
that now stop startup. The configuration guide, the Edge Cookie setup
guide, the error reference, the Fastly guide and the key rotation guide
all move from [ec.providers.hmac] to [ec.hmac], and the environment
override for that passphrase becomes
TRUSTED_SERVER__EC__HMAC__PASSPHRASE, which is the path the settings now
hold it at.

The configuration guide's [ec] reference needed more than a rename. Its
rule that every selection must have a matching block is no longer what
the code does, because a provider has a block only when it has settings,
so it now says which providers need one and which do not, and it explains
the implementation key that lets a block carry a label of the operator's
choosing. Its provider list and its validation notes follow the
snake_case names, and the resolve_allowed_origins key this stack added to
the [ec] section is documented alongside the rest.

The Edge Cookie guide named the host-signal and demonstration providers
by their old spellings throughout, including in a diagram label, and now
names them host_signals and client_fixed. The cargo feature that compiles
the demonstration provider in keeps the name client-fixed-demo, because a
cargo feature name is not a configuration value.

The example configuration's commented-out host-signal block carried both
the old table and the old name, and is now [ec.host_signals] selected by
provider = "host_signals".

Tests. cargo fmt --all -- --check is clean and cargo clippy -p
trusted-server-core --all-targets --all-features -- -D warnings passes.
The core suite passes 2,909 tests and 8 doc-tests with 4 ignored. The
Axum adapter passes 64 tests across its five binaries, cargo clippy-axum
is clean, and cargo check -p trusted-server-adapter-fastly --target
wasm32-wasip1 builds.

Four sentences in the guides joined their clauses with a semicolon, and
one table row grew past its column. They now read as one sentence each,
and the table is realigned, so the pages follow the house style the rest
of the guide follows.

Brings in the eight commits main gained since this branch was cut, of which
three touch the same code as the provider seam.

The parser-aware body hold gives every adapter a second entry point,
`build_state_with_services`, so a caller can supply the `RuntimeServices`
each request uses. The composition-root check the seam added now runs in
that function rather than in `build_state_with_settings`, and it is given
whatever provider those supplied services already carry instead of always
`None`, so a caller that resolved one is not made to resolve it twice.

On Cloudflare and Spin the state keeps both the provider this branch
resolves once at start-up and the services main lets a caller supply. The
free function this branch added is gone and its one job, handing the
resolved provider to every request, moved into `services_for_request`,
which is the method main introduced for the same purpose.

The core README this branch corrected one line of has been rewritten
wholesale by the documentation refresh, and the section that line was in no
longer exists, so main's version is taken as it stands.

Carries up the resolutions from split/1, where main's second entry point,
`build_state_with_services`, meets the composition-root provider check.

This branch had already given that check and `build_reusable_provider` a
`host_signals` argument, so each call now passes `None` for host signals and
whatever provider a caller's supplied services already carry. The free
function that handed the resolved provider to every request is gone on both
adapters and its job sits in `services_for_request`, the method main added,
which passes the settings this branch made `build_runtime_services` take.

Carries up the resolutions from split/2 and settles what main's own changes
mean for the permission model.

The adapters keep both the permission signal providers this branch resolves
at start-up and the services main lets a caller supply, and
`services_for_request` passes the providers to `build_runtime_services`, so
a request served from supplied services and one served from the request
context see the same schemes.

Main added tests for `allows_ec_creation`, `has_explicit_ec_withdrawal` and
`gate_eids_by_consent`, all three of which this branch replaced with the
permission model, so those tests name functions that no longer exist and
have not been taken. The behaviour the new one covers, stripping every EID
when personalised advertising is not permitted, is already asserted here by
`gate_eids_strips_eids_when_a_required_permission_is_unset`, which reaches
it through the resolved permissions rather than through the consent context.

The no-op HTML post processor in the registry tests goes with
`IntegrationHtmlPostProcessor`, the trait main removed in favour of
per-document stream processors.

Carries up the resolutions from split/3. Nothing on this branch touches the
code main changed, so the merge needed no decision of its own.

Carries up the resolutions from split/4.

Main's documentation refresh rewrote the section table in the configuration
guide, so its version is taken with this branch's sections added in
alphabetical order. That is device and geo, which the old table listed, and
permission_signal, which it never did.

The per-request Edge Cookie test builds AppState by hand, and the merge left
it without the field the supplied-services path added. It drives the
per-request path, so it supplies none.

Main added a Next.js auction fixture that every adapter now shares. This
branch refuses a document that configures an Edge Cookie provider without
saying where its readers are, because otherwise every request resolves at the
top of the rules tree, so the fixture acknowledges single-jurisdiction
operation the way the other fixtures on this branch do.

Main's new template cache test drives withdrawal with a Californian GPC
signal and asserts the Edge Cookie is expired. On this branch that signal
suppresses use without expiring anything, which
`finalize_gpc_suppresses_headers_but_keeps_the_cookie` states as deliberate,
because a visitor who later withdraws the opt-out keeps their identity. Only
an explicit withdrawal of device storage is destructive.

The test is about one template variant being shared across identities and
across withdrawal, not about how withdrawal is signalled, so it now says it
withdrew storage and keeps asserting the same thing. `EcContext` gains the
test constructor for saying so, since the gated one gives suppression.